<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: &lt;code&gt;ndk-stack&lt;/code&gt;</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__debugging__n_d_k-_s_t_a_c_k.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title"><code>ndk-stack</code> </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Introduction</h2>
<p>This document describes the 'ndk-stack' tool that is distributed with the Android NDK, since release r6.</p>
<h2>Overview</h2>
<p>'ndk-stack' is a simple tool that allows you to filter stack traces as they appear in the output of '<code>adb logcat</code>' and replace any address inside a shared library with the corresponding &lt;source-file&gt;:&lt;line-number&gt; values.</p>
<p>In a nutshell, it will translate something like: </p>
<pre class="fragment">      I/DEBUG   (   31): *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
      I/DEBUG   (   31): Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys'
      I/DEBUG   (   31): pid: 351, tid: 351  %gt;%gt;%gt; /data/local/ndk-tests/crasher &lt;&lt;&lt;
      I/DEBUG   (   31): signal 11 (SIGSEGV), fault addr 0d9f00d8
      I/DEBUG   (   31):  r0 0000af88  r1 0000a008  r2 baadf00d  r3 0d9f00d8
      I/DEBUG   (   31):  r4 00000004  r5 0000a008  r6 0000af88  r7 00013c44
      I/DEBUG   (   31):  r8 00000000  r9 00000000  10 00000000  fp 00000000
      I/DEBUG   (   31):  ip 0000959c  sp be956cc8  lr 00008403  pc 0000841e  cpsr 60000030
      I/DEBUG   (   31):          #00  pc 0000841e  /data/local/ndk-tests/crasher
      I/DEBUG   (   31):          #01  pc 000083fe  /data/local/ndk-tests/crasher
      I/DEBUG   (   31):          #02  pc 000083f6  /data/local/ndk-tests/crasher
      I/DEBUG   (   31):          #03  pc 000191ac  /system/lib/libc.so
      I/DEBUG   (   31):          #04  pc 000083ea  /data/local/ndk-tests/crasher
      I/DEBUG   (   31):          #05  pc 00008458  /data/local/ndk-tests/crasher
      I/DEBUG   (   31):          #06  pc 0000d362  /system/lib/libc.so
      I/DEBUG   (   31):
</pre><p>Into the more readable output: </p>
<pre class="fragment">      ********** Crash dump: **********
      Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys'
      pid: 351, tid: 351  &gt;&gt;&gt; /data/local/ndk-tests/crasher &lt;&lt;&lt;
      signal 11 (SIGSEGV), fault addr 0d9f00d8
      Stack frame #00  pc 0000841e  /data/local/ndk-tests/crasher : Routine zoo in /tmp/foo/crasher/jni/zoo.c:13
      Stack frame #01  pc 000083fe  /data/local/ndk-tests/crasher : Routine bar in /tmp/foo/crasher/jni/bar.c:5
      Stack frame #02  pc 000083f6  /data/local/ndk-tests/crasher : Routine my_comparison in /tmp/foo/crasher/jni/foo.c:9
      Stack frame #03  pc 000191ac  /system/lib/libc.so
      Stack frame #04  pc 000083ea  /data/local/ndk-tests/crasher : Routine foo in /tmp/foo/crasher/jni/foo.c:14
      Stack frame #05  pc 00008458  /data/local/ndk-tests/crasher : Routine main in /tmp/foo/crasher/jni/main.c:19
      Stack frame #06  pc 0000d362  /system/lib/libc.so
</pre><h2>Usage</h2>
<p>To do this, you will first need a directory containing symbolic versions of your application's shared libraries. If you use the NDK build system (i.e. ndk-build), then these are always located under <code>$PROJECT_PATH/obj/local/&lt;abi&gt;</code>, where <code>&lt;abi&gt;</code> stands for your device's ABI (i.e. '<code>armeabi</code>' by default).</p>
<p>You can feed the logcat text either as direct input to the program, e.g.: </p>
<pre class="fragment">    adb logcat | $NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi
</pre><p>Or you can use the -dump option to specify the logcat as an input file, e.g.: </p>
<pre class="fragment">    adb logcat &gt; /tmp/foo.txt
    $NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi -dump foo.txt
</pre><p>** IMPORTANT **:</p>
<blockquote class="doxtable">
<p>The tool looks for the initial line containing starts in the logcat output,</p>
<p></p>
</blockquote>
<p>i.e. something that looks like: </p>
<pre class="fragment">    *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
</pre><p>When copy/pasting traces, don't forget this line from the traces, or ndk-stack won't work correctly.</p>
<h2>TODO</h2>
<p>A future version of '<code>ndk-stack</code>' will try to launch '<code>adb logcat</code>' and select the library path automatically. For now, you'll have to do these steps manually.</p>
<p>As of now, ndk-stack doesn't handle libraries that don't have debug information in them. It may be useful to try to detect the nearest function entry point to a given PC address (e.g. as in the libc.so example above). </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
